# Rover

The `<Rover>` is a utility component that manages focus between items.

## Import

```jsx
import { Rover } from 'bumbag';
```

## Usage

```jsx-live
<Rover.State>
  <Group>
    <Rover use={Button}>
      Button 1
    </Rover>
    <Rover use={Button} disabled>
      Button 2
    </Rover>
    <Rover use={Button}>
      Button 3
    </Rover>
    <Rover use={Button}>
      Button 4
    </Rover>
  </Group>
</Rover.State>
```

### Controlled

```live
###tab=Hook,type=function-live
function Example() {
  const rover = Rover.useState();

  return (
    <React.Fragment>
      <Group>
        <Rover {...rover} use={Button}>
          Button 1
        </Rover>
        <Rover {...rover} use={Button} disabled>
          Button 2
        </Rover>
        <Rover {...rover} use={Button}>
          Button 3
        </Rover>
        <Rover {...rover} use={Button}>
          Button 4
        </Rover>
      </Group>
    </React.Fragment>
  )
}
###

###tab=Render Props,type=jsx-live
<Rover.State>
  {rover => (
    <React.Fragment>
      <Group>
        <Rover {...rover} use={Button}>
          Button 1
        </Rover>
        <Rover {...rover} use={Button} disabled>
          Button 2
        </Rover>
        <Rover {...rover} use={Button} disabled focusable>
          Button 3
        </Rover>
        <Rover {...rover} use={Button}>
          Button 4
        </Rover>
        <Rover {...rover} use={Button}>
          Button 5
        </Rover>
      </Group>
    </React.Fragment>
  )}
</Rover.State>
###
```

### Accessing internal state

Any descendant component of `Rover.State` can utilise `Rover.useContext` to access the [internal rover state](#roverstate-return-values):

```jsx
function Example() {
  const { rover } = Rover.useContext();

  return (
    <Button onClick={rover.hide}>Hide rover</Button>
  )
}
```

## Props

### Rover Props

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">disabled</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Same as the HTML attribute.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">focusable</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

When an element is `disabled`, it may still be `focusable`. It works
similarly to `readOnly` on form elements. In this case, only
`aria-disabled` will be set.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">id</Code>** <Code fontSize="100" palette="primary">string</Code> 

Same as the HTML attribute.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">stopId</Code>** <Code fontSize="100" palette="primary">string</Code> 

Element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

<details><Box use="summary" marginBottom="major-2"><strong>13 state props</strong></Box>
<blockquote>These props are returned by the state hook. You can spread them into this component (<code>...state</code>) or pass them separately. You can also provide these props from your own state logic.</blockquote>

**<Code fontSize="150" marginRight="major-1">baseId</Code>** <Code fontSize="100" palette="primary">string</Code> 

ID that will serve as a base for all the items IDs.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Defines the orientation of the rover list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">currentId</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

The current focused element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">first</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the first element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">last</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the last element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">move</Code>** <Code fontSize="100" palette="primary">(id: string, unstable_silent?: boolean) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to a given element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">next</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the next element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">previous</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the previous element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">stops</Code>** <Code fontSize="100" palette="primary">Stop[]</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

A list of element refs and IDs of the roving items.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">register</Code>** <Code fontSize="100" palette="primary">(id: string, ref: RefObject&#60;HTMLElement&#62;) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Registers the element ID and ref in the roving tab index list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">unregister</Code>** <Code fontSize="100" palette="primary">(id: string) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Unregisters the roving item.

<Divider marginTop="major-2" marginBottom="major-2" />

</details>

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>Box</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">use</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">className</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">children</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | number
  | boolean
  | {}
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<...>)>
  | ReactNodeArray
  | ReactPortal
  | ((props: BoxProps) => ReactNode)`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignX</Code>** <Code fontSize="100" palette="primary">&#34;right&#34; | &#34;left&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignY</Code>** <Code fontSize="100" palette="primary">&#34;top&#34; | &#34;bottom&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">variant</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">colorMode</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">overrides</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 96 more ...;
  Template?: TemplateThemeConfig;
}`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">elementRef</Code>** <Code fontSize="100" palette="primary">((instance: any) =&#62; void) | RefObject&#60;any&#62;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">themeKey</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

## State

### Rover.State API

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">baseId</Code>** <Code fontSize="100" palette="primary">string</Code> 

ID that will serve as a base for all the items IDs.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">currentId</Code>** <Code fontSize="100" palette="primary">string</Code> 

The current focused element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Defines the orientation of the rover list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">loop</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

If enabled:

   - Jumps to the first item when moving next from the last item.
   - Jumps to the last item when moving previous from the first item.

<Divider marginTop="major-2" marginBottom="major-2" />

### Rover.State Return Values

<!-- Automatically generated -->

<details><Box use="summary" marginBottom="major-2"><strong>18 values</strong></Box>

**<Code fontSize="150" marginRight="major-1">baseId</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

ID that will serve as a base for all the items IDs.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Defines the orientation of the rover list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">stops</Code>** <Code fontSize="100" palette="primary">Stop[]</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

A list of element refs and IDs of the roving items.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">currentId</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

The current focused element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">loop</Code>** <Code fontSize="100" palette="primary">boolean</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

If enabled:

   - Jumps to the first item when moving next from the last item.
   - Jumps to the last item when moving previous from the first item.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">setBaseId</Code>** <Code fontSize="100" palette="primary">(value: SetStateAction&#60;string&#62;) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Sets `baseId`.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">register</Code>** <Code fontSize="100" palette="primary">(id: string, ref: RefObject&#60;HTMLElement&#62;) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Registers the element ID and ref in the roving tab index list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">unregister</Code>** <Code fontSize="100" palette="primary">(id: string) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Unregisters the roving item.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">move</Code>** <Code fontSize="100" palette="primary">(id: string, unstable_silent?: boolean) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to a given element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">next</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the next element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">previous</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the previous element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">first</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the first element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">last</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the last element.

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
    

### Rover.useState API

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">baseId</Code>** <Code fontSize="100" palette="primary">string</Code> 

ID that will serve as a base for all the items IDs.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">currentId</Code>** <Code fontSize="100" palette="primary">string</Code> 

The current focused element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Defines the orientation of the rover list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">loop</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

If enabled:

   - Jumps to the first item when moving next from the last item.
   - Jumps to the last item when moving previous from the first item.

<Divider marginTop="major-2" marginBottom="major-2" />

### Rover.useState Return Values

<!-- Automatically generated -->

<details><Box use="summary" marginBottom="major-2"><strong>18 values</strong></Box>

**<Code fontSize="150" marginRight="major-1">baseId</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

ID that will serve as a base for all the items IDs.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Defines the orientation of the rover list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">stops</Code>** <Code fontSize="100" palette="primary">Stop[]</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

A list of element refs and IDs of the roving items.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">currentId</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

The current focused element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">loop</Code>** <Code fontSize="100" palette="primary">boolean</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

If enabled:

   - Jumps to the first item when moving next from the last item.
   - Jumps to the last item when moving previous from the first item.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">setBaseId</Code>** <Code fontSize="100" palette="primary">(value: SetStateAction&#60;string&#62;) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Sets `baseId`.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">register</Code>** <Code fontSize="100" palette="primary">(id: string, ref: RefObject&#60;HTMLElement&#62;) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Registers the element ID and ref in the roving tab index list.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">unregister</Code>** <Code fontSize="100" palette="primary">(id: string) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Unregisters the roving item.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">move</Code>** <Code fontSize="100" palette="primary">(id: string, unstable_silent?: boolean) =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to a given element ID.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">next</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the next element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">previous</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the previous element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">first</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the first element.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">last</Code>** <Code fontSize="100" palette="primary">() =&#62; void</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Moves focus to the last element.

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
    

## Theming

 <Theme
  component={'Rover'}
  overrides={[
    {
      key: 'Rover.styles.base',
      props: {
        stopId: 'rover',
        stops: [],
        currentId: null,
        register: () => {},
        unregister: () => {},
        move: () => {},
        next: () => {},
        previous: () => {},
        first: () => {},
        last: () => {}
      }
    }
  ]}>
  Hello world
</Theme>
